<!--
/**
 * @file CronTools.html
 * @author Alejandro Dario Simi
 * @date $Date: 2013-08-05 00:26:28 +0000 (Mon, 05 Aug 2013) $
 *
 * $Id: CronTools.html 100 2013-08-05 00:26:28Z daemonraco@gmail.com $
 * $URL: http://wcomix.googlecode.com/svn/tags/wcomix-1.0/docs/CronTools.html $
 */
-->
<html>
	<head>
		<title>Cron Tools</title>
		<link rel="stylesheet" type="text/css" href="docs.css"/>
		<script type="text/javascript" src="jquery-1.8.0.min.js"></script>

		<script type="text/javascript" src="SyntaxHighlighter/scripts/shCore.js"></script>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shCoreEclipse.css"/>
		<link type="text/css" rel="stylesheet" href="SyntaxHighlighter/styles/shThemeEclipse.css"/>
		<script type="text/javascript">SyntaxHighlighter.all();</script>

		<script type="text/javascript" src="docs.js"></script>
	</head>
	<body>
		<div class="Section">
			<span class="Title">Table Of Contents</span>
			<div class="TableOfContents"></div>
		</div>
		<div class="Section">
			<span class="Title">Cron</span>
			<div class="Paragraph">
				<p>One of the most important pieces of wcomix is its cron tools set. These tools are a set of PHP scripts that can be run
				only from a terminal or from some other application like "[L:http://en.wikipedia.org/wiki/Cron::cron]" in UNIX-like and
				Windows<sup>TM</sup> operative systems, and they perform different tasks needed to keep the wcomix site consistent.</p>
				<p>wcomix provide a central script called "cron.php" saved along with the other tools into "[VA:$wcROOTDIR]/cron". This
				central script will use a descriptor called [VA:$wcCronScripts] to call all needed tools and execute them in the right order</p>
				<p>Further in this page, these tools will be presented and explained the need for them to run periodically.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Cron Tools</span>
			
			<span class="SubTitle">Updating List</span>
			<div class="Paragraph">
				<p>"<strong>lists.update</strong>"</p>
				<p>Basically, this tool performs two tasks:<ul>
					<li>seek and load new comics and directories</li>
					<li>mark lost comics and directories</li>
				</ul></p>
				<p>The seeking and loading comics and directories task consist in look inside every directory configured in every group
				and insert all comic names into table [CO:comics] and all directory names into table [CO:directories]. This operation is
				requiered because it's the only way to add new comics and directories to wcomix. This kind of behavior is quicker in
				performance than reading a directory, but it requires to keeps the list up to date, otherwise, new comics won't be shown
				anywhere in the wcomix site. This is the main reason for a first cron execution when wcomix is being installed.</p>
				<p>The second task it performs is to mark every comic listed in table [CO:comics] and directory in [CO:directories] that
				is no longer phisically at its path. This operation allows the administrator to check and correct this kind of issues.</p>
				<p>Directories keep the last modification date store in database, this allows this cron tool to re-check only when
				something changed in a directory.</p>
			</div>
			
			<span class="SubTitle">Updating Comic's Names</span>
			<div class="Paragraph">
				<p>"<strong>comic.updatenames</strong>"</p>
				<p>This method check every comic that has its column 'cmc_next_name' with a value and phisically renames it to that
				name.</p>
			</div>

			<span class="SubTitle">Updating Directory's Names</span>
			<div class="Paragraph">
				<p>"<strong>directory.updatenames</strong>"</p>
				<p>This cron tool is similar to 'comic.updatenames' and does the same for directories having their column 'dir_next_name'
				with a value.</p>
			</div>

			<span class="SubTitle">Running Rules</span>
			<div class="Paragraph">
				<p>"<strong>rules.run</strong>"</p>
				<p>This cron tool executes every tag rule configured in the table [CO:rules] and from them, each enabled action. As you
				may read in section "[L:Rules_Actions.html::Rules &amp; Actions]", these rules are related to extensions installed in the
				wcomix site, for example, extension 'TagsRelator'.</p>
			</div>

			<span class="SubTitle">Updating NOTAG entries</span>
			<div class="Paragraph">
				<p>"<strong>autotag.updateNOTAG</strong>"</p>
				<p>This is a simple cron tool that checks every comic and it has no tags, it assigns a special tag called 'Untagged'.</p>
			</div>

			<span class="SubTitle">Updating FEWTAGS entries</span>
			<div class="Paragraph">
				<p>"<strong>autotag.updateFEWTAGS</strong>"</p>
				<p>This cron tool is similar to 'autotag.updateNOTAG' because it checks every comic and it has less than a specific number
				tags, it adds a special tag called 'Few Tags'. Special tags 'Untagged' and 'Few Tags' are excluded from tags count.</p>
				<p>This cron tool allows to set a different minimum number of tags for each group using a configuration lile the next one:</p>
				<pre class="brush: php;">
$wcDefaults["class-WCTagsUpdateFEWTAGS"]                    = array();
$wcDefaults["class-WCTagsUpdateFEWTAGS"]["group-limits"]    = array();
$wcDefaults["class-WCTagsUpdateFEWTAGS"]["group-limits"][2] = 10;</pre>
				<p>This configuration sets a minimum of ten tags for the group with ID '2'.</p>
			</div>

			<span class="SubTitle">Moving Trash Into Trashcan</span>
			<div class="Paragraph">
				<p>"<strong>garbage.move</strong>"</p>
				<p>This tool visits every group that has a trash-can directory defined and move into it all the garbage.</p>
				<p>Garbage is any comic tagged with the special tag 'Garbage'.</p>
			</div>

			<span class="SubTitle">Finding Losts</span>
			<div class="Paragraph">
				<p>"<strong>lists.losts</strong>"</p>
				<p>This cron tool looks for inconsistencias on the database. This is a list of the things it checks:<ul>
					<li>[CO:lost comics]: Comics that belong to a non existing directory. It activates comic's lost flag.</li>
					<li>[CO:lost members]:<ul>
						<li>Tag members of non existing tags. It removes those members associations.</li>
						<li>Tags associated to non existing comics and comics marked as lost. It breaks the association.</li>
					</ul></li>
					<li>[CO:empty tags]: Tags with no members. It removes those tags unless they are specials or locked by a
					rule action.</li>
					<li>[CO:no collection comics]: Comics that belong to a non existing collection. It set a no-collection
					to the comic.</li>
					<li>[CO:no collection collections]: Collections that belong to a non existing collection. It set a no-collection
					to the collection.</li>
					<li>[CO:no trash-can]: It detects groups where its trash can in no in table [CO:directories]. Adds it to the
					list of directories.</li>
					<li>[CO:no read rates]: Reads and ratings of non existing comics. It removes the association.</li>
				</ul></p>
			</div>

			<span class="SubTitle">Update Statistics</span>
			<div class="Paragraph">
				<p>"<strong>statistics.update</strong>"</p>
				<p>This cron tool is able to update many counts inside database. Those count are:<ul>
					<li>Tag's members count</li>
					<li>Directory's members count</li>
					<li>Comic's global reads and rates (automatic)</li>
				</ul></p>
			</div>
			
			<span class="SubTitle">Previews</span>
			<div class="Paragraph">
				<p>"<strong>previews.update</strong>"</p>
				<p>Almost no item in wcomix generates a preview image instantly, they just use a default image configured by
				{VA:$wcDefaults["preview"]}. Nontheles, this cron tool allows to seek items lacking their previews and tries to
				generate them. This kind of behavior is to avoid a delay on pages response time.</p>
				<p>Anyway, when a site is new or if there was a lot of changes between two executions of this tool, a large amount
				of comics may require the regeneration of all their previews and it may incurs in too much time spent on this operation.
				To avoid this kind of situations, this cron tool will generate previews for a maximum number of comics on each execution
				depending on a value stored in {VA:$wcDefaults["max-autoexpand"]}.</p>
			</div>
			
			<span class="SubTitle">Seach Engine</span>
			<div class="Paragraph">
				<p>"<strong>search.updateindex</strong>"</p>
				<p>Every new item in the database won't appear on the search page unless they are indexed. This cron tool triggers that
				indexation for all unindexed items.</p>
			</div>
		</div>
		<div class="Section">
			<span class="Title">Cron Configuration</span>
			
			<span class="SubTitle">Cron Descriptor</span>
			<div class="Paragraph">
				<p>If it's necesary, a developer can add an arbitrary operation to be run when cron is executed. For this purpose, a
				new entry must be added in the descriptor [VA:$wcCronScripts] following the next structure:</p>
				<pre class="brush: php;">$wcCronScripts[] = array(
        "name"          => "TITLE",
        "url"           => "http://www.example.com/TOOL/", // Optional
        "class"         => "CLASS_NAME",
        "path"          => "FULL_PATH.php",                // Optional
        "params"        => array(                          // Optional
                "PARAM1",
                "PARAM2"),
        "auto"          => true,
        "enabled"       => true
);
</pre>
				Where:<ul>
					<li>[CO:name] is a title to be shown where the tool is run.</li>
					<li>[CO:url] is URL address where to find more information about this cron tool.</li>
					<li>[CO:class] is the class in charge of performing all tasks. It must be a WCCronTool inherited class.</li>
					<li>[CO:path] must be full path to a PHP script containing the logic to be executed periodically.</li>
					<li>[CO:params] List of arguments to be provided when the script is run.</li>
					<li>[CO:auto] is a flag that can be executed through a cron profile (true) or if it must be executed
					directly and alone (false).</li>
					<li>[CO:enabled] is a flag that indicates if this tool can be used.</li>
				</ul></p>
			</div>

			<span class="SubTitle">Cron Profiles</span>
			<div class="Paragraph">
				<p>Cron tools use another descriptor called [VA:$wcCronProfiles] that holds lists of cron tool's names associated
				with an ID. These IDs are called cron profiles and the determine what to run when '[VA:$wcROOTDIR]/cron/cron.php'
				is called.</p>
				<p>By default, wcomix provides three cron profiles and they are:<ul>
					<li><strong>default</strong><ul>
						<li>garbage.move</li>
						<li>comic.updatenames</li>
						<li>directory.updatenames</li>
						<li>lists.update</li>
						<li>rules.run</li>
						<li>autotag.updateNOTAG</li>
						<li>autotag.updateFEWTAGS</li>
						<li>lists.losts</li>
						<li>previews.update</li>
						<li>search.updateindex</li>
						<li>statistics.update</li>
					</ul></li>
					<li><strong>tagger</strong><ul>
						<li>rules.run</li>
						<li>autotag.updateNOTAG</li>
						<li>autotag.updateFEWTAGS</li>
						<li>previews.update</li>
						<li>search.updateindex</li>
					</ul></li>
					<li><strong>names</strong><ul>
						<li>comic.updatenames</li>
						<li>directory.updatenames</li>
						<li>previews.update</li>
						<li>search.updateindex</li>
					</ul></li>
				</ul></p>
				<p>Also, there's a variable called [VA:$wcCronProfile] that holds the cron profile name to be used when
				'[VA:$wcROOTDIR]/cron/cron.php' is called without parameters. By default, it contains "[CO:default]" as a value.</p>
			</div>
		</div>
	</body>
</html>